從回答程式問題到參與開發工作

最簡單的 AI 輔助開發是從一個問題開始，開發者貼上一段程式碼、錯誤訊息或需求，請 AI 解釋語法、找出問題，或產生一小段範例。

這種方式會得到開發的相關提示，開發者仍要自行找到關聯檔案、加入程式碼、執行測試，再判斷結果能否使用。

Codex 是 OpenAI 為軟體開發工作設計的程式開發代理人（Coding Agent），能查看目錄與檔案、搜尋相關程式、執行終端機（Terminal）命令，並根據執行結果繼續處理任務。

開發者可以直接交付一個目標，例如「找出登入失敗的原因並提出修正」，Codex 會依序閱讀程式碼、搜尋相關位置、修改內容並進行驗證。

這兩種使用方式可以出現在同一段開發過程中。遇到陌生語法時，可以把 Codex 當成對話助手。需要理解一項功能或完成範圍清楚的修改時，也可以讓它直接進入專案環境工作。

差異主要來自 Codex 能取得的專案資訊與可以執行的動作。當它能讀取整個專案時，分析可以納入檔案之間的關係，也能利用實際執行結果修正先前的判斷。

這項能力也會改變開發者交付任務的方式。「這段程式在做什麼」只會產生文字說明結果。「閱讀這個儲存庫，找出登入流程、相關測試與可執行命令」則是一項具有明確範圍與檢查結果的開發任務。

使用 Codex 時，任務目標、工作範圍與預期產出都需要寫清楚。這些資訊會直接影響 Codex 如何搜尋程式碼、採取哪些動作，以及最後交付什麼結果。

開發代理人如何讀取與處理專案

開發代理人會在任務中反覆觀察、行動與檢查。Codex 先讀取目錄結構、設定檔與說明文件，再依照任務目標搜尋相關程式碼。找到線索後，它可以執行建置、測試或靜態檢查命令，並根據執行結果調整下一步，直到完成任務。

透過這個循環，Codex 可以處理跨越多個檔案的工作，也會留下命令結果與檔案差異供開發者檢查。

以訂單專案為例，Codex 可以先從路由設定找到訂單介面，再追到服務層、資料存取程式與測試檔案。若任務要求說明取消訂單流程，它會整理請求從哪裡進入、規則在哪裡判斷、資料如何更新，以及哪些測試正在保護這段行為。這些原本需要開發者逐一搜尋的線索，可以先由 Codex 整理成一份可檢查的說明。

Codex Cloud 會為任務建立隔離的雲端環境，取出指定的儲存庫與分支，完成環境設定後開始執行任務。任務完成後，介面會顯示執行摘要與檔案差異。開發者可以繼續要求補充，也可以在確認結果後建立拉取請求（Pull Request）。

Codex 整理出的內容仍可能漏掉動態載入、外部服務，或沒有記錄在專案中的團隊知識。開發者仍然需要回到程式碼、設定與命令輸出核對結果。若 Codex 修改了檔案，也要審查差異內容與測試結果。

Codex 可以負責執行任務、整理線索與提供驗證結果，開發者仍要確認任務方向、檢查變更內容，並決定是否接受結果。

第一次使用 Codex Cloud 理解程式碼儲存庫

我們先使用網頁版 Codex，讓任務在 Codex Cloud 的隔離環境中執行，並完成一次專案探索。

請選擇已連接到 Codex Cloud 的 GitHub 小型儲存庫。專案規模以能在短時間內看完主要內容為宜，並優先選擇同時包含說明文件、程式碼與測試的練習專案。

這次任務只會讀取與整理資訊，不會要求 Codex 修改任何檔案。

在 Codex Cloud 建立新任務後，選擇儲存庫與對應環境，再輸入以下提示詞：

請閱讀這個程式碼儲存庫，不要修改任何檔案。整理一份「專案理解摘要」，內容需要說明專案用途、主要模組及其責任、測試檔案的位置，以及可以從現有設定或文件確認的建置、啟動與測試命令。每項結論請附上依據的檔案路徑。無法從儲存庫確認的內容請明確標示，不要自行補充假設。

送出任務後，可以從執行紀錄查看 Codex 讀取了哪些檔案、搜尋了哪些關鍵字，以及執行過哪些命令。

Codex Cloud 的工作流程會包含連接程式碼儲存庫、建立專案環境、描述預期成果，以及查看任務摘要與檔案差異。雲端環境也可以設定相依套件、工具與環境變數，讓後續任務使用一致的開發條件。

如果摘要缺少測試命令，可以要求 Codex 回頭檢查套件設定、建置腳本或持續整合設定。若列出的模組過多，也可以要求只保留與主要使用流程直接相關的部分。

這些追問可以練習如何修正 Codex 的工作方向，也能觀察它會根據哪些檔案、設定與命令結果建立對專案的理解。

檢查「專案理解摘要」是否可靠

一份可用的專案理解摘要，需要回到儲存庫核對正確性。專案用途可以引用 README、套件描述或啟動入口，主要模組需要附上目錄或檔案路徑，測試位置需要說明採用的測試工具與命名方式，執行命令則應來自套件腳本、建置檔或持續整合設定。若缺少這些依據，後續修改時仍難以確認內容是否可靠。

開發者可以抽查兩到三項結論。先開啟 Codex 提到的檔案，確認路徑與內容是否相符。再選一個不會修改資料的命令，例如列出測試或顯示說明，確認命令是否存在。

無法在目前環境安全執行的命令，可以先標示為「尚未驗證」，不要把 AI 的推測當做是已確認的結果。

這次練習先停在理解階段，觀察 Codex 如何取得線索、整理資訊並附上依據。專案用途、模組位置、測試路徑與常用命令，都會成為後續任務的重要背景。

開始修改程式後，開發者可以利用這份摘要界定工作範圍，並確認 Codex 是否找到正確的檔案與流程。

實作 - 專案理解摘要

實作步驟

1. 開啟 Codex Cloud。
   

2. 與 GitHub 建立連線
   

3. 輸入提示詞
   

4. 檢視結果
   

結果範例

1. 專案用途

這是一個小型的 TypeScript 命令列工具（Issue Triage CLI），用途是讀取 JSON 格式的 issue 清單，根據下列因素計算每個 issue 的優先分數，並依處理優先順序輸出：

• 嚴重程度（severity）
• 受影響使用者數（affected users）
• 等待天數（age）
• 是否已有替代處理方式（workaround）

上述用途由 README 的專案說明直接確認。

套件本身也被描述為「依 triage 優先度排列 issues 的 TypeScript CLI」，目前版本為 0.1.0，且標記為私人套件、不供 npm 公開發布。

2. 執行流程

整體資料流如下：

1. CLI 從第一個命令列參數取得 JSON 檔案路徑；若未提供，便回報正確用法。
2. 讀取並解析 JSON 檔案，再交給 domain 層進行結構與欄位驗證。
3. triage service 計算分數、配置優先標籤並排序。
4. CLI 輸出排序結果、issue 總數及 interrupt 數量。
5. 發生讀檔、JSON 解析或輸入驗證錯誤時，CLI 會將錯誤訊息寫到標準錯誤輸出，並把程序結束碼設為 1。

3. 主要模組與責任

src/domain/issue.ts：領域型別與輸入驗證

此模組負責：

• 定義可接受的嚴重程度：low、medium、high、critical。

• 定義原始 issue 的必要欄位：

  • id
  • title
  • severity
  • affectedUsers
  • ageDays
  • hasWorkaround

• 定義排序後新增的 priorityScore 與 priorityLabel；標籤共有 monitor、schedule、expedite、interrupt 四種。

• 驗證最外層輸入必須是 JSON 陣列，並逐筆解析 issue。

• 驗證字串不可為空、嚴重程度必須受支援、數字必須為有限的非負值，以及布林欄位必須確實為 boolean。

src/services/triage.ts：評分、排序、摘要與格式化

此模組負責：

• 定義嚴重程度的基本權重：

  • low: 10
  • medium: 25
  • high: 50
  • critical: 80

• 為每個 issue 計算優先分數與標籤，再按分數由高至低排序；若分數相同，則按 issue ID 排序。

• 產生摘要，包括 issue 總數、interrupt 數量，以及排序第一的 issue。

• 將排序結果格式化成 CLI 可讀文字；空清單會輸出 No issues to triage.。

• 使用以下公式組成分數：

  • 嚴重程度權重
  • 受影響使用者數除以 10，最高計 30 分
  • 等待天數乘以 1.5，最高計 20 分
  • 有 workaround 時扣 15 分
  • 最後四捨五入成整數

• 根據分數門檻配置標籤：

  • >= 90：interrupt
  • >= 65：expedite
  • >= 35：schedule
  • 其餘：monitor

src/cli.ts：命令列進入點

此模組負責將其他模組串接起來，包括：

• 接收輸入檔路徑。
• 非同步讀取 UTF-8 JSON 檔案。
• 呼叫 parseIssues、rankIssues 與 summarizeTriage。
• 格式化並輸出結果。
• 統一處理執行錯誤。

examples/issues.json：範例輸入

儲存庫提供一份包含三筆 issue 的可執行範例，涵蓋 critical、high 和 low 嚴重程度，以及有、無 workaround 的情況。

README 也記載了 CLI 所需的 JSON 陣列和各個必要欄位格式。

4. 測試檔案位置與涵蓋範圍

目前確認到的測試檔案只有：

• tests/triage.test.ts

它使用 Vitest，測試以下行為：

1. 分數由高至低排序，以及高優先項目取得 interrupt 標籤。
2. 分數相同時，以 issue ID 作為排序依據。
3. 摘要中的 issue 總數、interrupt 數量及最高順位 issue。
4. 空清單與非空清單的文字格式化結果。
5. 非陣列輸入及缺少有效 ID 等錯誤輸入的拒絕行為。

TypeScript 設定會同時納入 src/**/*.ts 和 tests/**/*.ts，因此型別檢查涵蓋原始碼及測試碼。

5. 建置、啟動與測試命令

環境需求與安裝

• Node.js 版本需求：Node.js 20 或以上。
• 安裝依賴：

npm install

此命令由 README 明確記載。

開發模式啟動

npm run dev -- ./examples/issues.json

dev script 實際執行 tsx src/cli.ts，後面的 JSON 路徑會成為 CLI 輸入參數。 README 也以範例資料檔記載相同啟動方式。

本次實際執行後，範例中的三筆 issue 被依序標記為 interrupt、expedite、monitor，且程序成功結束。

建置

npm run build

此 script 執行：

tsc -p tsconfig.json

設定可由 package.json 直接確認。 TypeScript 編譯目標為 ES2022、採用 NodeNext 模組與解析模式、啟用 strict mode，輸出目錄為 dist。

由於 tsconfig.json 同時包含 src 與 tests，依目前設定推論，建置輸入不只應用程式原始碼，也包含測試 TypeScript 檔案；這是根據 include 與 rootDir 設定得出的結論。

本次未執行建置命令，因為它會產生 dist/，違反「不要修改任何檔案」的要求。dist/ 也明確列在 .gitignore 中。

測試

npm test

此 script 執行 vitest run。 本次執行結果為 1 個測試檔案、5 個測試全部通過。

靜態型別檢查

npm run check

此 script 執行 tsc --noEmit，因此只做 TypeScript 型別檢查，不產生編譯輸出。 本次執行成功。

6. 無法從儲存庫確認的內容

以下項目在目前檔案中沒有可確認的設定或文件，因此不作額外假設：

• 正式環境啟動命令：package.json 沒有 start script；只能確認 dev、build、test、check 四個 script。
• 發布或部署流程：沒有看到部署 script 或相關文件；套件目前標記為 private: true。
• CI/CD 設定：目前檢閱到的專案檔案中沒有可確認的 CI 工作流程。
• 測試覆蓋率門檻或 coverage 命令：雖然 .gitignore 排除了 coverage/，但 package.json 並未定義 coverage script，因此無法確認實際覆蓋率工具或門檻。
• 端對端測試、整合測試或 CLI 專屬測試：目前唯一測試檔主要直接測試 domain 與 triage service；沒有看到直接啟動 CLI 程序的自動化測試。
• 授權條款、貢獻規範及架構決策文件：目前 README 僅說明用途、結構、命令與輸入格式。

檢閱與驗證

• ✅ find .. -name AGENTS.md -print（未找到額外的儲存庫操作指示）
• ✅ find . -type f -not -path './.git/*' -not -path './node_modules/*' | sort
• ✅ nl -ba README.md
• ✅ nl -ba package.json
• ✅ nl -ba tsconfig.json
• ✅ nl -ba .gitignore
• ✅ find src tests examples -type f | sort
• ✅ npm test（1 個測試檔案、5 項測試全部通過）
• ✅ npm run check（TypeScript 型別檢查通過）
• ✅ npm run dev -- ./examples/issues.json（範例 CLI 成功執行）
• ✅ git status --short --branch（工作樹保持乾淨，未修改任何檔案）

依照要求，本次沒有修改或提交任何檔案，也沒有建立 Pull Request。